.TH gtlssh-keygen 1 01/02/19  "Key handling for gtlssh"
.SH NAME
gtlssh-keygen \- Key handling for gtlssh
.SH SYNOPSIS
.B gtlssh-keygen [options] <command> [command options]
.SH DESCRIPTION
The
.BR gtlssh-keygen
program is used for making key handling for gtlssh easier.

Generally, when you start using gtlssh on a system, you would run

  gtlssh-keygen keygen

and it would create keys for you.  You should do the same thing on any
target system you want to log into with gtlssh.  Then copy the
default.crt file in your $HOME/.gtlssh directory to the target's
$HOME/.gtlssh/allowed_certs directory.  Then run

  gtlssh rehash

on the target system to generate the hashes   After that you should be
able to log in without a password.

When you need to regenerate your keys, you run

  gtlssh-keygen keygen

again.  It will prompt you for replacement.  If you replace the keys,
the old keys will be saved with a ".1" appended to the filename.  Once
you replace they keys, you need to push up new keys to all your
target.  You can run

  gtlssh-keygen pushcert target1 [target2 [....]]

to update they keys on all those targets.  It will use the old
credentials (with the ".1" appended) to do this, so it should work
easily.
.SH DIFFERENCES FROM SSH
Unlike ssh, ssl keys have lifetimes.  By default gtlssh creates 1 year
lifetimes on keys, though you can override this.  Although this is a
little annoying, it is a good idea to replace your keys periodically,
so you could call this a good thing.

gtlssh lets you create keys for specific targets and use them
automatically.  Suppose, for instance, that you want to use a
different key for logging into target abc.my.domain.  You would do:

  gtlssh-keygen keygen abc.my.domain

and it would create a key and certificate in the
directory .gtlssh/keycerts with the names abc.my.domain.crt and
abc.my.domain.key.  You would need to copy that certificate (not the
default.crt) to your remote target.
.B gtlssh
would see that those keys were there and use them automatically when
you logged in to abc.my.domain.  The pushcert command understands
this, too, and will handle pushing the proper keys when you push to
abc.my.domain.

You can also add ports to the key generation, and it will only use it
if you connect to the specific target on the specific port.  This
could be useful for ser2net.
.SH OPTIONS
.TP
.I \-\-keysize size
Create an RSA key with the given number of bits.  Default is 2048.
Usually 1024, 2048, or 4096.
.TP
.I \-\-keydays days
Create a key that expires in the given number of days.  Default is 365.
.TP
.I \-\-basedir dir
Base directory for gtlssh.  Default is $HOME/.gtlssh.
Default keys go here.
.TP
.I \-\-keydir dir
Location to put the non-default generated keys.  Default is
$HOME/.gtlssh/keycerts
.TP
.I \-\-commonname name
Set the common name in the certificate.  The default is your username
for normal certificates and the fully qualified domain name for server
certificates.
.TP
.I \-\-force | \-f
Don't ask any questions, just force the operations.  Be careful, this
will overwrite data without asking.
.TP
.I \-h|\-\-help
Help output
.SH "COMMAND"
Commands are:
.TP
.I keygen [-p <port>] [hostname]
Setup of the base directory (if not already set up) and create keys.
If nothing is specified, create the default key in
<basedir>/default.key and <basedir>/default.crt.  Otherwise create
keys in the form <keydir>/<host>[,<port>].key and
<keydir>/<host>[,<port>].crt.
.TP
.I setup
Like keygen, but take no options and create the default certificate
only.
.TP
.I rehash [directory [directory [...]]]
The openssl library used by gtlssh requires that certificates in a
library be hashed so it can find them.  This command redoes the hashes
in the given directories.  If no directory is specified, it rehashes
<basedir>/allowed_certs and <basedir>/server_certs.

Note that if you add keys to these directories, you must rehash them
or they will not work.

.I rehash
will automatically remove any certificates that have expired.
.TP
.I addallow [-i] <hostname> <file>
Add the given file as an allowed public certificate for the given
hostname.  It will install this file in the directory in
<basedir>/allowed_certs with the name "hostname.crt".  It will
also rehash the directory.  If
.I -i
is specified, input comes from stdin and the file is not required or
used.  If the destination file already exists, it will rename it
"hostname.crt.1.crt".
.TP
.I pushcert [-n <name> ] [-p <port>] <hostname> [[-p <port>] <hostname> [...]]
Put the local certificate for the given host onto the remote host so
it can be used for login.  It uses old credentials (credentials
with .1 appended to the name, per keygen) if they are there.  This is
useful if you have upated your certificate and need to send a new one
to some remote hosts.  It finds the certificate name as described in
the keygen command.  If old credentials exist, it will use those to
connect with gtlssh and send the certificate.  Otherwise it will use
default credentials and hope for the best, probably only useful if
passwords are accepcted.  This only works one keygen back, if you have
run the keygen command twice for the host, you will need to transfer
the certificate manually.  By default the credential on the remote
host is named the output of 'hostname -f' on the local machine,
.I -n
overrides this.
.TP
.I serverkey
Create keys for the server, generally in /etc/gtlssh/gtlsshd.key and
/etc/gtlssh/gtlsshd.crt.  You generally must be root to do this.  Use
for initial setup of gtlsshd.
.SH "SEE ALSO"
gtlssh(1), gtlsshd(8)
.SH "KNOWN PROBLEMS"
None.
.SH AUTHOR
.PP
Corey Minyard <minyard@acm.org>
